SOLO BUTTON — MAC HANDOFF KIT
Version 1.0.0 | September 30, 2026

WHAT YOU NEED

- A button already flashed with the Solo Button v1 firmware, plus USB power.
- A Mac with Bluetooth and Solo installed. Windows/Linux are not supported here.
- Python 3.11–3.14 installed from https://www.python.org/downloads/macos/
  (or an existing compatible Homebrew installation).
- Internet during setup to download the pinned Bluetooth Python dependencies.

This is a source-script handoff kit, not a signed/notarized Mac application.
The button uses Bluetooth for both commands and status; it does not need USB data.
No Arduino/firmware tools are needed by the recipient.

ONE-TIME SETUP

1. Open Solo. In its settings, enable the local HTTP API. No MCP server is needed.
2. Power the button. If it is still paired with its previous owner, hold its button
   for 10 seconds to clear pairing. Pair “Solo Button” in Mac Bluetooth settings.
   Only have the intended button powered during first setup if possible.
3. Keep this whole folder together. Double-click “Setup Solo Button.command”.
   It opens Terminal, explains what will be installed, and asks you to type yes.
   macOS may ask for Bluetooth access; allow it for this local bridge to work.
4. Setup lists available buttons. Enter yours, then confirm its amber ring is the
   one you intend to control. Setup saves THAT device, not the sender's device.
5. After setup, tap the button: Solo should come forward and receive Cmd–Shift–E.
   In Solo 0.7.1, this opens Unreads. Shortcut behavior can vary with Solo version.
6. Optionally paste AGENT PROMPT.txt into a local agent chat in Solo. It adds more
   precise task states when that agent follows the instructions.

If a Mac security warning prevents running downloaded scripts, stop and review
the files with someone you trust. This kit does not disable Gatekeeper or remove
quarantine protections. Do not run an unfamiliar modified copy.

DAILY USE AND COLORS

The bridge starts at login and reconnects. Solo's local API must remain enabled.

Pulsing blue: Bluetooth disconnected.
Steady dim blue: no active processes, or an explicit “ready” task report.
Pulsing cyan: a process is running/starting/stopping, or explicit “working”.
Pulsing amber: the agent explicitly needs your attention.
Red: a process reports “failed”, or the agent explicitly reports an error.
Pulsing purple: bridge heartbeat missing or Solo's API is unavailable.
Brief white flashes: connection or physical button press.

Automatic mode observes ALL Solo processes. A persistent server may keep it cyan.
A stopped/exited process is not proof of success. Precise task completion and
needs-attention states require the optional agent prompt. Overrides expire after
five minutes and cannot hide an unavailable Solo API. One ring shows one state;
the latest explicit report wins. This version supports one button per Mac bridge.

THE GENERIC STATUS COMMAND

"$HOME/.local/bin/solo-status" working
"$HOME/.local/bin/solo-status" attention
"$HOME/.local/bin/solo-status" ready
"$HOME/.local/bin/solo-status" error
"$HOME/.local/bin/solo-status" auto

Using this home-relative path works even if ~/.local/bin is not in the agent's
PATH. Setup intentionally does not edit any shell profile.

WHAT SETUP INSTALLS

~/Library/Application Support/SoloButton/
  Private Python environment, bridge code, and local runtime/configuration files.
~/.local/bin/solo-status
  Status command used by the agent prompt.
~/Library/LaunchAgents/com.crumbls.solo-button.plist
  Per-user login startup, with logs in SoloButton/runtime/launch.log.

No administrator access or cloud service is required by the bridge. Solo API
credentials stay on this Mac. Only status codes and press sequences cross
Bluetooth. Setup installs dependencies from PyPI; it does not bundle Python.
The original handoff folder may be moved after installation. Do not move/remove
the installed Python runtime itself; the private environment relies on it.

TROUBLESHOOTING

- Run Diagnostics.command. It checks the installation, login service, API access,
  and recent logs without printing the Solo API token.
- Run Start Bridge.command to restart a configured bridge.
- Run Stop Bridge.command to stop it and disable login startup. Start restores it.
- Purple: make sure Solo is open, HTTP API is enabled, and Bluetooth permission
  is allowed for the bridge's Python process. No need to enable Solo's MCP server.
- Missing custom Bluetooth service after a firmware change: forget ONLY this
  Solo Button entry and pair it again. Do not remove unrelated Bluetooth devices.
- Replacing the physical button: stop the bridge, then run in Terminal:
  "$HOME/Library/Application Support/SoloButton/.venv/bin/python" "$HOME/Library/Application Support/SoloButton/bridge/solo_bridge.py" --bind
  Then run Start Bridge.command.
- Existing-install warning: setup refuses to overwrite any existing bridge or
  command, including an earlier developer setup. Do not delete a working install.
  Ask for migration help rather than running two bridges for the same button.
- Setup failed before completion: check the error first. If this was a NEW install,
  use Stop Bridge.command if a login service was created, then move ONLY the three
  exact installation items listed above (and any .plist.disabled version) to Trash
  before retrying. Keep an existing working installation untouched.
- Uninstall: Stop Bridge.command, then move those same exact items to Trash.
  They can be restored from Trash; no recursive deletion command is needed.

VERIFICATION AND LIMITS

The underlying firmware/bridge was tested on macOS 15.3.1 with Solo 0.7.1 and
Python 3.14. Button presses, status colors, and Bluetooth reconnect were verified.
This portable installer is additionally tested with temporary installation paths
and simulated system operations. It has not been installed on a second person's
Mac yet. Different macOS/Solo versions may require adjustments.

No firmware is included here: give this kit with an already-programmed button.
The original developer's working bridge is not modified by creating this folder.

For developers: PYTHONPATH=bridge python3 -m unittest discover -s tests -v
The tests include a temporary localhost-only HTTP server.
